Compile-time dependency

To use Errai UI Navigation, you must include it on the compile-time classpath. If you are using Maven for your build, add these dependencies:

    <dependency>
      <groupId>org.jboss.errai</groupId>
      <artifactId>errai-navigation</artifactId>
      <version>${errai.version}</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>org.jboss.errai</groupId>
      <artifactId>errai-cdi-client</artifactId>
      <version>${errai.version}</version>
      <scope>provided</scope>
    </dependency>

If you are not using Maven for dependency management, add errai-navigation-version.jar to the compile-time classpath of a project that's already set up for Errai UI templating.

GWT Module Descriptor

Once you have Errai UI Navigation on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's *.gwt.xml file:

   <inherits name="org.jboss.errai.ui.nav.Navigation"/>

Declaring a Page

To declare a page, annotate any subclass of Widget with the @Page annotation:

@Page
public class ItemListPage extends Composite {
  // Anything goes...
}

By default, the name of a page is the simple name of the class that declares it. In the above example, the ItemListPage will fill the navigation panel whenever the browser's location bar ends with #ItemListPage. If you prefer a different page name, use the @Page annotation's path attribute:

@Page(path="items")
public class ItemListPage extends Composite {
  // Anything goes...
}

@Page(startingPage=true)
public class WelcomePage extends Composite {
  // Anything goes...
}

@Page
public class ItemPage extends VerticalPanel {

  @PageShowing
  private void preparePage() {
  }

  @PageHiding
  private void unpreparePage() {
  }

  // Anything goes...
}

@Page
public class ItemPage extends VerticalPanel {

  @PageState
  private int itemId;

  // Anything goes...
}

Declaring a Link with TransitionAnchor

The easiest way to declare a link between pages is to inject an instance of TransitionAnchor<P>, where P is the class of the target page.

Here is an example declaring an anchor link from the templated welcome page to the item list page. The first code sample would go in WelcomePage.java while the second would go in the WelcomePage.html, the associated html template.

@Page(startingPage=true)
@Templated
public class WelcomePage extends Composite {

  @Inject @DataField TransitionAnchor<ItemListPage> itemLink;

}

<div>
  <a data-field="itemLink">Go to Item List Page</a>
</div>

You can inject any number of links into a page. The only restriction is that the target of the link must be a Widget type that is annotated with @Page. When the user clicks the link Errai will transition to the item list page.

Declaring a Manual Link

Sometimes it is necessary to manually transition between pages (such as in response to an event being fired). To declare a manual link from one page to another, inject an instance of TransitionTo<P>, where P is the class of the target page.

This code declares a manual transition from the welcome page to the item list page:

@Page(startingPage=true)
public class WelcomePage extends Composite {

  @Inject TransitionTo<ItemListPage> startButtonClicked;

}

You do not need to implement the TransitionTo interface yourself; the framework creates the appropriate instance for you.

As with TransitionAnchor, the only restriction is that the target of the link must be a Widget type that is annotated with @Page.

Following a Manual Link

To follow a manual link, simply call the go() method on an injected TransitionTo object. For example:

@Page(startingPage=true)
public class WelcomePage extends Composite {

  @Inject TransitionTo<ItemListPage> startButtonClicked;

  public void onStartButtonPressed(ClickEvent e) {
    startButtonClicked.go();
  }
}

Installing the Navigation Panel into the User Interface

Beginning in version 2.4, Errai will automatically attach the Navigation Panel to the Root Panel, but it is possible to override this behaviour by simply adding the Navigation Panel to another component manually. The best time to do this is during application startup, for example in the @PostConstruct method of your @EntryPoint class. By using the default behaviour you can allow Errai Navigation to control the full contents of the page, or you can opt to keep some parts of the page (headers, footers, and sidebars, for example) away from Errai Navigation by choosing an alternate location for the Navigation Panel.

The following example reserves space for header and footer content that is not affected by the navigation system:

@EntryPoint
public class Bootstrap {

  @Inject
  private Navigation navigation;

  @PostConstruct
  public void clientMain() {
    VerticalPanel vp = new VerticalPanel();
    vp.add(new HeaderWidget());
    vp.add(navigation.getContentPanel());
    vp.add(new FooterWidget());

    RootPanel.get().add(vp);
  }
}

This last example demonstrates a simple approach to defining the page structure with an Errai UI template. The final product is identical to the above example, but in this case the overall page structure is declared in an HTML template rather than being defined programmatically in procedural logic:

@Templated
@EntryPoint
public class OverallPageStrucutre extends Composite {

  @Inject
  private Navigation navigation;

  @Inject @DataField
  private HeaderWidget header;

  @Inject @DataField
  private SimplePanel content;

  @Inject @DataField
  private FooterWidget footer;

  @PostConstruct
  public void clientMain() {

    // give over the contents of this.content to the navigation panel
    content.add(navigation.getContentPanel());

    // add this whole templated widget to the root panel
    RootPanel.get().add(this);
  }

}

Overriding the default Nagivating Panel type

By default Errai uses {{com.​google.​gwt.​user.​client.​ui.SimplePanel}} as a container for navigation panel. Sometimes this is not sufficient and users would prefer using another implementation. For example a com.google.gwt.user.client.ui.SimpleLayoutPanel that manages child size state.

To provide your own implementation of the navigation panel you must implement org.jboss.errai.ui.nav.client.local.NavigatingContainer. For example:

public class NavigatingPanel implements NavigatingContainer {

  SimplePanel panel = new SimpleLayoutPanel();

  public void clear() {
    this.panel.clear();
  }

  public Widget asWidget() {
    return panel.asWidget();
  }

  public Widget getWidget() {
    return panel.getWidget();
  }

  public void setWidget(Widget childWidget) {
    panel.add(childWidget);
  }

  public void setWidget(IsWidget childWidget) {
    panel.add(childWidget);
  }

}

Then in your GWT module descriptor you need to override the default navigation panel (org.jboss.errai.ui.nav.client.local.NavigatingContainer) by adding:

<replace-with class="com.company.application.client.NavigatingPanel">
  <when-type-is class="org.jboss.errai.ui.nav.client.local.NavigatingContainer"/>
</replace-with>

Viewing the Generated Navigation Graph

Because the pages and links in an Errai Navigation application are declared structurally, the framework gets a complete picture of the app's navigation structure at compile time. This knowledge is saved out during compilation (and at page reload when in Dev Mode) to the file .errai/navgraph.gv. You can view the navigation graph using any tool that understands the GraphViz (also known as DOT) file format.

One popular open source tool that can display GraphViz/DOT files is GraphViz. Free downloads are available for all major operating systems.

When rendered, a navigation graph looks like this:

In the rendered graph, the pages are nodes (text surrounded by an ellipse). The starting page is drawn with a heavier stroke. The links are drawn as arrows from one page to another. The labels on these arrows come from the Java field names the TransitionTo objects were injected into.